HydroData is an R package that lets users find, download and explore earth system data for an area of interest (AOI). The core input the user needs is their AOI. HydroData offers three paramaters to define an AOI. These include state, county, and clip_unit. The following document provides examples on how to use these parameters to define an AOI for data extraction:

Method 1: Defining an AOI by state

A state name or abbrivaiation can be used to define an AOI.

CA = getAOI(state = 'CA')

Multiple states can also be queried:

WestCoast = getAOI(state = c("Oregon", "Washington", "CA"))

Method 2: Defining an AOI by County

Defining an AOI by county requires a state as well

EP = getAOI(state = "CO", county = "El Paso")

Multiple counties can also be queried:

centralCoast = getAOI(state ="CA", county = c("Santa Barbara", "San Luis Obispo", "Ventura"))

Method 3: The clip_unit

In HydroData a clip_unit is a region that can be used to subset data. Most commonly, this is a bounding box or a user supplied shapefile - both of which can be input as a clip_unit. To build a bounding box in HydroData clip unit has five potential inputs:

  1. Location
  2. Bounding box height (miles)
  3. Bounding box width (miles)
  4. location origin (optional)

Inputs must be provided as a list, and order DOES matter. Examples for each input follow:

The clip_unit list()

1. Location

A Location is the first input for a clip_unit list. It can be given as a colloquial name or as a lat, long pair. Names are geocoded via the Google API and the dismo package.

Grand Canyon (Location example):

Here we look at the Grand Canyon, using both the name and the lat,long found with a Google search.Notice the slightly different locations are generated:

GC_name = getAOI(clip_unit = list("grand canyon", 10, 10))

GC_lat_lon = getAOI(clip_unit = list(36.0544, -112.1401, 10, 10))

2. Bounding box height and width

The next two values in a clip_unit list are a bounding box height and width in miles. The first entry defines height and the second width:

National Water Center (bounding box diminsions example):

nwc.tall = getAOI(clip_unit = list("National Water Center, AL", 30, 10))
nwc.wide = getAOI(clip_unit = list("National Water Center, AL", 10, 30))
nwc = dismo::geocode("National Water Center, AL")

3. Origin

In previous examples, bounding boxes are generated using the location as a centroid. You can change this by adding a final argument to the clip_unit list specifying where the location lies in reference to the bounding box. Options include ‘center’, ‘lowerleft’, ‘lowerright’, ‘upperleft’, ‘upperright’:

UCSB (origin example):

ucsb.c =  getAOI(clip_unit =  list("UCSB", 10, 10, "center"))
ucsb.ul = getAOI(clip_unit = list("UCSB", 10, 10, "upperleft"))
ucsb.ur = getAOI(clip_unit = list("UCSB", 10, 10, "upperright"))
ucsb.ll = getAOI(clip_unit = list("UCSB", 10, 10, "lowerleft"))
ucsb.lr = getAOI(clip_unit = list("UCSB", 10, 10, "lowerright"))

Clip_unit by User Shapefile

While overkill here… It is worth noting that a shapefile can be used as input for the clip_unit parameter

Santa Monica (user shapefile example):

LA = rgdal::readOGR("/Users/mikejohnson/Documents/GitHub/Communities1/Communities.shp")
## OGR data source with driver: ESRI Shapefile 
## Source: "/Users/mikejohnson/Documents/GitHub/Communities1/Communities.shp", layer: "Communities"
## with 353 features
## It has 13 fields
## Integer64 fields read as strings:  X_CENTER Y_CENTER
SM = LA[LA$LABEL_CITY == 'Santa Monica',] %>% spTransform(HydroDataProj)

AOI = getAOI(clip_unit = SM)

Practical Examples:

Up until this point, example have been shown using getAOI(). This function is built into every HydroData function allowing users to define their AOI in a consistent fashion for every data type they want. Three examples following showing how AOI’s are defined within the context of function and more example can be found at the vignette here.

Find all Army Corps Dams from the Natonal Inventory of Dams within Texas using state:

dams = findNID(state = 'Texas')
## AOI defined as the boundary of Texas. Shapefile determined. Now loading loading NID database...
## All dams in CONUS loaded: 73,999 dams in total
## 7,242 NID dams found in boundary of Texas
## Returned list includes: NID dams shapefile
explore(dams)

Find all water bodies intersecting a 100 square mile area to the northwest of Cheyenne Wyoming using a clip_unit list():

lakes = findWaterbodies(clip_unit = list("Cheyenne, Wyoming", 100, 100, origin = "lowerright"))
## AOI defined as the supplied clip unit.
## Shapefile determined.
## Loading North American Water Bodies
## Trying URL ...
## All water bodies loaded: 14,488 in total.
## 14 water bodies found within supplied clip unit
## Returned list includes: water bodies shapefile
explore(lakes) %>% addPolygons(data = getAOI(clip_unit = list("Cheyenne, Wyoming", 100, 100, origin = "lowerright")), fillColor = 'transparent', color = 'black')

Find all GHCN station recording precipitation in Santa Monica using a shapefile:

prcp = findGHCN(clip_unit = SM, parameters = 'PRCP')
## AOI defined as the supplied clip unit. Loading global GHCN data...
## 4 GHCN stations found in supplied clip unit
## Returned list includes: NOAA GHCN shapefile
explore(prcp) %>% addPolygons(data = SM, fillColor = "transparent", color = 'black')